home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / program / pcl4w13.zip / PCL4WUSR.DOC < prev    next >
Text File  |  1996-07-14  |  80KB  |  2,245 lines

  1.  
  2.  
  3.                   Personal Communications Library
  4.  
  5.                            For Windows
  6.  
  7.  
  8.                              (PCL4W)
  9.  
  10.  
  11.  
  12.                           USERS MANUAL
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                            Version 1.3
  19.  
  20.                            July 8, 1996
  21.  
  22.  
  23.  
  24.  
  25.                  This software is provided as-is.
  26.           There are no warranties, expressed or implied.
  27.  
  28.  
  29.  
  30.  
  31.                        Copyright (C) 1996
  32.                        All rights reserved
  33.  
  34.  
  35.  
  36.                    MarshallSoft Computing, Inc.
  37.                        Post Office Box 4543
  38.                        Huntsville AL 35815
  39.  
  40.                        Voice : 205-881-4630
  41.                          FAX : 205|880|0925
  42.                          BBS : 205-880-9748
  43.                        email : info@marshallsoft.com
  44.                          web : www.marshallsoft.com
  45.  
  46.                            _______
  47.                       ____|__     |                (R)
  48.                    --+       |    +-------------------
  49.                      |   ____|__  |  Association of
  50.                      |  |       |_|  Shareware
  51.                      |__|   o   |    Professionals
  52.                    --+--+   |   +---------------------
  53.                         |___|___|    MEMBER
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  PCL4W Users Manual                                                Page 1
  69.                        C O N T E N T S
  70.  
  71.  
  72.  
  73.  
  74.  
  75.   Chapter                                                   Page
  76.  
  77.   1.0 Introduction................................................3
  78.       1.1 User Support............................................4
  79.       1.2 ASP Ombudsman...........................................4
  80.       1.3 A Typical Application...................................5
  81.       1.4 Determining UART Address & IRQ Settings.................6
  82.       1.5 Disabling Windows Ports.................................6
  83.       1.6 Installation............................................7
  84.   2.0 Library Organization........................................8
  85.       2.1 Configuration...........................................8
  86.       2.2 Initialization & Termination............................8
  87.       2.3 Modem Control & Status..................................9
  88.       2.4 Serial I/O..............................................9
  89.       2.5 Error Detection........................................10
  90.       2.6 General Support........................................10
  91.   3.0 Library Overview...........................................11
  92.       3.1 Dynamic Link Libraries.................................11
  93.       3.2 DOS Protected Mode Interface...........................11
  94.       3.3 Memory Models..........................................11
  95.       3.4 Using the Library......................................11
  96.       3.5 Using a MAKEFILE.......................................12
  97.       3.6 Using an IDE...........................................12
  98.       3.7 Making the Library.....................................12
  99.   4.0 Talking to Your Modem......................................13
  100.       4.1 Modem Standards........................................13
  101.       4.2 Flow Control...........................................14
  102.       4.3 Modem I/O Functions....................................15
  103.       4.4 Modem Initialization...................................17
  104.   5.0 Problems...................................................18
  105.   6.0 Serial Communications......................................19
  106.       6.1 Communications Basics..................................19
  107.       6.2 Standard Port Addresses................................20
  108.       6.3 Running 3 or 4 Ports Concurrently......................21
  109.       6.4 Using Multiport Boards.................................22
  110.           6.4.1 Using the Digiboard..............................22
  111.           6.4.2 Using the BOCA board.............................22
  112.       6.5 Transmitter Interrupts.................................23
  113.       6.6 RS232 Signals..........................................24
  114.       6.7 National INS8250, INS16450, and INS16550 UARTs.........25
  115.       6.8 Register Summary.......................................26
  116.   7.0 Example Programs...........................................28
  117.       7.1 SIMPLE.................................................28
  118.       7.2 LOGIN..................................................28
  119.       7.3 SELFTEST...............................................28
  120.       7.4 TERM...................................................28
  121.   8.0 Legal Issues...............................................29
  122.       8.1 Registration...........................................29
  123.       8.2 License................................................30
  124.       8.3 Warranty...............................................30
  125.   9.0 Summary....................................................31
  126.       9.1 Revision History.......................................31
  127.       9.2 Function Summary.......................................32
  128.       9.3 Further Reading........................................33
  129.  10.0 Other MarshallSoft Computing products for C/C++............33
  130.       10.1 The Personal Communications Library for C/C++.........33
  131.       10.2 Libraries for Other Languages.........................33
  132.  
  133.  
  134.  
  135.  
  136.  PCL4W Users Manual                                                Page 2
  137.   1.0 Introduction
  138.  
  139.  
  140.   The  Personal  Communications Library for Windows (PCL4W) is an asynchronous
  141.   communications dynamic link library (DLL) for software developers using  the
  142.   Microsoft  Windows  C/C++  compiler,  the  Borland  Windows compiler, or the
  143.   WATCOM Windows compiler. Other Windows compilers may  also  work.   A  80386
  144.   machine or higher is recommended.
  145.  
  146.  
  147.   o 30+ communications functions.
  148.   o Supports the high performance INS16550 UART.
  149.   o Supports the PC/4 and PC/8 DigiBoard.
  150.   o Supports the BOCA BB1004, BB1008, and BB2016 boards.
  151.   o Supports hardware (RTS/CTS) flow control.
  152.   o Use any IRQ (IRQ0-IRQ15) with any UART address.
  153.   o Interrupt driven receiver & (optionally) transmitter.
  154.   o Supports 300 baud to 115,200 baud.
  155.   o Supports COM1 through COM20.
  156.   o Adjustable queues from 8 bytes to 32 KB.
  157.   o Control-BREAK error exit.
  158.   o 18 communications error conditions trapped.
  159.   o Allows 4 ports to run concurrently (more with Digi/BOCA board).
  160.   o Complete modem control & status.
  161.   o Written in assembly language for small size & high speed.
  162.   o Terminal program featuring ASCII (with XON/XOFF), XMODEM,
  163.     YMODEM, & YMODEM-G.
  164.  
  165.  
  166.   Why should you buy PCL4W? Consider the following:
  167.  
  168.      COMPLETE  :  PCL4W is complete since it provides absolute control of the
  169.                   serial ports (including the high performance INS16550).
  170.  
  171.       COMPACT  :  PCL4W is very compact at less than 6 KB.  Your  application
  172.                   doesn't carry a lot of excess code.
  173.  
  174.          FAST  :  PCL4W is fast.  It will run at 115200 baud on all 80386 and
  175.                   up machines.
  176.  
  177.       SUPPORT   : If  you  get  stuck,   you will talk to the programmer that
  178.                   wrote the code, not a person hired to answer the phone.
  179.  
  180.           BBS  :  A user support BBS is available (2400 to 14400 baud, N81) in
  181.                   order to provide immediate support as necessary.
  182.  
  183.    NEWSLETTER  :  Our newsletter "COMM TALK" is published quarterly (available
  184.                   online)   which   discusses   communications   problems  and
  185.                   solutions.
  186.  
  187.         PRICE  :  You get PCL4W for a very reasonable price !
  188.  
  189.      UPGRADES  :  Once  you  buy  PCL4W,  you can always update  to  the most
  190.                   recent version for a very reasonable cost.
  191.  
  192.    COMPATIBLE  :  PCL4W  is  call  for call compatible with the MSDOS based
  193.                   version PCL4C except for two functions in which delay  times
  194.                   are no longer necessary.
  195.  
  196.  
  197.   Our goal is to provide a robust serial communications library that that  you
  198.   and your customers can depend upon.
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  PCL4W Users Manual                                                Page 3
  205.   1.1 User Support
  206.  
  207.  
  208.   We want you to be successful in developing your applications using PCL4W! We
  209.   depend on our customers to let us know what they need  in  a  communications
  210.   library.   This  means we are committed to providing the best communications
  211.   library that we can. If you have any suggestions or comments, please let  us
  212.   know.
  213.  
  214.   If you are having a problem using PCL4W, call  us  at  205-881-4630  between
  215.   1:30PM  and  9:30PM  CST  Monday  through Friday. You can also call at other
  216.   times and leave a message, and call back  later  for  a  reply.   Registered
  217.   users (ONLY) can also FAX us at 205-880-0925 at any time (24 hours).
  218.  
  219.   However,  we  can  only  answer  questions  with  respect to using the PCL4W
  220.   library.  We cannot help you program your application.
  221.  
  222.   You  may  also  call  our User Support BBS (2400 to 14400 baud, no parity, 8
  223.   data bits, 1 stop bit) at 205-880-9748 and leave a message  (address  it  to
  224.   the SYSOP).  We will usually have a reply ready for you within 24 hours.
  225.  
  226.   The BBS  is  available  24  hours  per  day  except  at  2  PM  Sundays  for
  227.   maintenanace. All files are in standard ZIP format. The BBS will contain the
  228.   latest  shareware  version  of  all MarshallSoft products as well as related
  229.   files such as:
  230.  
  231.        BUGS.ZIP:  Bug report.
  232.        NEWS.ZIP:  Latest news regarding our products.
  233.  
  234.   If you are on the Internet, you can email us at info@marshallsoft.com.   You
  235.   can  also  get  the  latest  versions of our products from our anonymous ftp
  236.   site:
  237.  
  238.         FTP:   ftp.marshallsoft.com
  239.        PATH:   marshallsoft
  240.  
  241.   The MarshallSoft  Computing,  Inc.   newsletter  "Comm  Talk"  is  published
  242.   quarterly.  It discusses various communications problems and solutions using
  243.   PCL4W  as  well  as related information.
  244.  
  245.   The   latest   copy   of our newsletter can be found on User Support BBS (in
  246.   file area "Newsletters"), our anonymous ftp site  (directory  /marshallsoft)
  247.   as well as our web site.
  248.  
  249.       Web site:  www.marshallsoft.com
  250.  
  251.  
  252.   1.2 ASP Ombudsman
  253.  
  254.  
  255.   MarshallSoft  Computing,  Inc.   is a member of the Association of Shareware
  256.   Professionals (ASP).  ASP wants to make sure that  the  shareware  principle
  257.   works  for  you.   If  you are unable to resolve a shareware-related problem
  258.   with an ASP member by contacting the member directly, ASP  may  be  able  to
  259.   help.  The  ASP  Ombudsman can help you resolve a dispute or problem with an
  260.   ASP member, but does not provide technical support  for  members'  products.
  261.   Please  write  to  the  ASP  Ombudsman  at 545 Grover Road, Muskegon, MI USA
  262.   49442-9427, Fax 616-788-2765, or send a CompuServe  message  via  CompuServe
  263.   Mail to ASP Ombudsman 70007,3536.
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  PCL4W Users Manual                                                Page 4
  273.   1.3 A Typical Application
  274.  
  275.  
  276.   In general, there are two classes of applications that use a  communications
  277.   library  like  PCL4W: those that use a modem to connect to the outside world
  278.   and those that connect directly to a peripheral device. In  either  case,  a
  279.   typical   application  program  using  PCL4W  might  consist  of  3  phases:
  280.   initialization, execution, and  termination.   The  following  code  segment
  281.   assumes a knowledge of the windows API.
  282.  
  283.   In  the  following  code  segment,  SioRxBuf is called to set up a 1024 byte
  284.   receive buffer; SioParms is called to set up the parity, stop bit count, and
  285.   word length; SioReset is called to set the baud rate to 9600 and  reset  the
  286.   UART (Universal Asynchronous Receiver / Transmitter).
  287.  
  288.  
  289.        case WM_CREATE:
  290.           /* initialization */
  291.           SioRxBuf(Port,RxBuffer,Size1024);
  292.           SioParms(Port,NoParity,OneStopBit,WordLength8);
  293.           SioReset(Port,Baud9600);
  294.  
  295.  
  296.   If you are using the version of  the  library  with  transmitter  interrupts
  297.   enabled  (PCL4W2.LIB),  then  SioTxBuf()  must  be  called  to  set  up  the
  298.   transmitter buffer. The transmit buffer must be distinct  from  the  receive
  299.   buffer.
  300.  
  301.  
  302.        case WM_CREATE:
  303.           /* initialization */
  304.           SioRxBuf(Port,TxBuffer,Size1024);
  305.           SioTxBuf(Port,RxBuffer,Size1024);
  306.           SioParms(Port,NoParity,OneStopBit,WordLength8);
  307.           SioReset(Port,Baud9600);
  308.  
  309.  
  310.   Characters can be  transmitted  and  received  once  the  required  port  is
  311.   initialized.   Before leaving your application, SioDone is called to restore
  312.   the prior state of the serial communications  system.   Forgetting  to  call
  313.   SioDone  before  exiting your application will leave the interrupt system in
  314.   an unuseable state and the machine will have to be re-booted.
  315.  
  316.  
  317.        case WM_DESTROY:
  318.           /* termination */
  319.           SioDone(Port);
  320.  
  321.  
  322.   If you are using a modem, you also need to be concerned  about  initializing
  323.   your  modem  correctly  and  handling  any  required flow control.  Refer to
  324.   Chapter 4.0, "Talking to Your Modem" for detailed information.
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  PCL4W Users Manual                                                Page 5
  341.   1.4 Determining UART Address & IRQ Settings
  342.  
  343.  
  344.   Both Windows 3.X and Windows 95 maintain a list of serial port settings.  On
  345.   Windows  3.X  systems, choose the "Ports" icon in the "Control Panel" in the
  346.   "Main Group".  Select "Settings", and then "Advanced" to view the  COM  port
  347.   UART address and IRQ settings.
  348.  
  349.   In Windows 95, choose "My Computer" icon ("or whatever your computer icon is
  350.   named), select the "Control Panel" folder and then the "System" icon.  Click
  351.   on  the "Device Manager" tab.  Click "Computer" and then click "Properties".
  352.   Click the "View Resources" tab.   To  view  reserved  resources,  click  the
  353.   resource  type at the top of the dialog box (i.e., "Interrupt request (IRQ)"
  354.   or "Input/output (I/O)" ).
  355.  
  356.  
  357.   1.5 Disabling Windows Ports
  358.  
  359.  
  360.   The Windows operating system virtualizes all serial ports that it  controls.
  361.   This  means  that  Windows  intercepts  reads  and writes to hardware ports,
  362.   resulting in significant slowdown. When Windows virtualizes a port, the UART
  363.   FIFO control register (FCR) can not be modified.
  364.  
  365.   Since  PCL4W  also  controls the hardware directly, it is best (although not
  366.   absolutely necessary) to disable Windows control of the serial ports and the
  367.   IRQs that will be used by PCL4W applications.
  368.  
  369.   The four standard COM ports which Windows typically controls are:
  370.  
  371.         Port  Address  IRQ
  372.         COM1   &H3F8    4
  373.         COM2   &H2F8    3
  374.         COM3   &H3E8    4
  375.         COM4   &H2E8    3
  376.  
  377.   Since COM1 and COM3 share an IRQ, if either is to be used by PCL4W then both
  378.   should be disabled from Windows control. Similarly for COM2 and COM4.
  379.  
  380.   To begin, exit from Windows completely. To disable the  serial  ports,  edit
  381.   the  [386Enh] section of the WINDOWS.INI file in the WINDOWS directory.  For
  382.   example, to disable COM1 and COM3,  add  the  following  to  the  [386  Ehn]
  383.   section:
  384.  
  385.         COM1Base=0
  386.         COM1Irq=-1
  387.         COM3Base=0
  388.         COM3Irq=-1
  389.  
  390.   Restart Windows after modifying SYSTEM.INI. This procedure does not apply to
  391.   multiport boards or any other serial ports unknown to Windows.
  392.  
  393.   16550 UARTS are really necessary when running under Windows, particularly at
  394.   baud  rate  above 19200.  The Microsoft Diagnostics (MSD) program can be run
  395.   which will report the type of UARTs installed on your machine.
  396.  
  397.   If a 16550 port MUST be shared with Windows, and you want the FIFO  enabled,
  398.   look for statements such as
  399.  
  400.         COM1FIFO=0
  401.  
  402.   in  the  [386Ehn] section of SYSTEM.INI and delete it.  However, the Windows
  403.   communications driver may have trouble with the FIFO, which is why there  is
  404.   a statement to disable it. This problem does not occur with PCL4W.
  405.  
  406.  
  407.  
  408.  PCL4W Users Manual                                                Page 6
  409.   1.6 Installation
  410.  
  411.  
  412.   (1) Before installation of PCL4W , your Windows C compiler should already be
  413.   installed on your system and tested. Examine the file "FILES.LST" for a list
  414.   of the distribution files.
  415.  
  416.   (2) Make a backup  copy  of  your  distribution  disk.   Put  your  original
  417.   distribution disk in a safe place.
  418.  
  419.   (3) Create a work directory on your hard drive. For  example,  to  create  a
  420.   work directory named PCL4W, type from DOS:
  421.  
  422.                    MKDIR PCL4W
  423.  
  424.   (4)  Copy  all  the  files from your backup copy of the distribution disk to
  425.   your work directory.  For example, to copy from the A: drive  to  your  work
  426.   directory, we type:
  427.  
  428.                   CD PCL4W
  429.                   COPY A:*.*
  430.  
  431.   (5)  Compile SIMPLE.C and link with the PCL4W library (PCL4W.LIB).
  432.  
  433.   Makefiles  and  project  files  are  provided  for  each  of  the  supported
  434.   compilers.
  435.  
  436.        Microsoft command line compiler:   NMAKE SIMPLE._M_
  437.        Borland command line compiler:     MAKER -fSIMPLE._B_
  438.        Watcom command line compiler:      WMAKE -f SIMPLE._W_
  439.  
  440.   NOTES: (1) Use NMAKE, not MAKE with Microsoft C
  441.          (2) Use MAKER, not MAKE with Borland C.
  442.  
  443.   Alternately, SIMPLE can be compiled in an Integrated Development Environment
  444.   (IDE)  such  as supplied by Microsoft, Borland, and Watcom. Refer to section
  445.   3.5 "Using an IDE" for more information.
  446.  
  447.   (6) The recommended way to test  SIMPLE  is  to  run  it  on  two  computers
  448.   connected  by  a null modem cable.  Whatever is typed on one computer should
  449.   be displayed on the other. If you don't have  two  computers,  you  can  use
  450.   SIMPLE  to talk to your modem. Sending an "AT" to the modem should result in
  451.   an "OK" being sent back. See section 7.1 "SIMPLE" for more information.
  452.  
  453.   (7) Compile and link LOGIN. Use LOGIN to call a local BBS. See  section  7.1
  454.   "LOGIN" for more information.
  455.  
  456.   (8)  Compile  and  link  SELFTEST.   Use SELFTEST to test one of your serial
  457.   ports. See section 7.3 "SELFTEST" for more information.
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  PCL4W Users Manual                                                Page 7
  477.   2.0 Library Organization
  478.  
  479.  
  480.   The  PCL4W  library  is organized into six categories of functions. Refer to
  481.   the PCL Reference Manual (PCL4W.REF) for details on individual functions.
  482.  
  483.  
  484.   2.1 Configuration
  485.  
  486.  
  487.   There  are three functions in the configuration category.  SioPorts sets the
  488.   number of PC and DigiBoard / BOCA ports.  SioUART is used to change the UART
  489.   base address for a communications port  to  a  non-standard  address,  while
  490.   SioIRQ  is  used  to  assign a nonstandard IRQ line to a port.  (See Section
  491.   6.2, Standard Port Addresses for more details on standard UART addresses and
  492.   IRQ lines).
  493.  
  494.   The  configuration  functions  SioPorts,  SioUART  and SioIRQ must be called
  495.   before calling any other library functions.   Be  very  careful  when  using
  496.   these  functions.   Remember that your serial hardware must support the UART
  497.   and IRQ that you specify.  Always test any new configuration immediately.
  498.  
  499.        SioPorts : Sets number of PC and DigiBoard / BOCA ports.
  500.        SioUART  : Sets the UART base address.
  501.        SioIRQ   : Assigns an IRQ line to a port.
  502.  
  503.   THE IRQ GOLDEN RULE: You may open (via  SioReset)  only  one  port  per  IRQ
  504.   (except for the DigiBoard / BOCA board).
  505.  
  506.  
  507.   2.2 Initialization & Termination
  508.  
  509.  
  510.   There  are  nine  functions  in the initialization and termination category.
  511.   Together, SioGetDiv, SioFIFO, SioRxBuf, SioTxBuf,  and  SioReset  initialize
  512.   your  serial communications system.  Your application must call SioParms and
  513.   SioRxBuf before calling SioReset, and SioReset must  be  called  before  any
  514.   serial I/O processing can be done.
  515.  
  516.   After initialization, SioParms and SioBaud can be called again to change the
  517.   communications  parameters without resetting the serial port. SioFlow can be
  518.   called to enable hardware flow control.
  519.  
  520.   Before exiting from your application, SioDone must  be  called.  Failure  to
  521.   call SioDone can crash your system later.
  522.  
  523.        SioRxBuf   : Sets up receive buffer.
  524.        SioTxBuf   : Sets up transmitter buffer.
  525.        SioFIFO    : Sets the interrupt level for the INS16550.
  526.        SioParms   : Sets parity, stop bits, and word length.
  527.        SioReset   : Initialize a serial port for processing.
  528.        SioDone    : Terminates further serial processing.
  529.        SioBaud    : Sets the baud rate of the selected port.
  530.        SioFlow    : Enables / disables flow control.
  531.        SioGetDiv  : Gets the baud rate divisor.
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  PCL4W Users Manual                                                Page 8
  545.   2.3 Modem Control & Status
  546.  
  547.  
  548.   There  are  eight  functions  in the modem control and status category which
  549.   provide your application with complete control over the status  and  control
  550.   bits of your modem.
  551.  
  552.   There  are  two modem control bits, "Data Terminal Ready" (DTR) and "Request
  553.   To Send" (RTS). These bits can be  read,  set,  or  cleared  by  SioDTR  and
  554.   SioRTS.
  555.  
  556.   There  are  four  modem status bits, "Data Set Ready" (DSR), "Clear To Send"
  557.   (CTS), "Ring Indicator" (RI), and "Data Carrier Detect" (DCD). SioModem  can
  558.   read  any  of  the modem status bits.  SioDSR, SioCTS, SioRI, and SioDCD can
  559.   only read their respective modem status bit.
  560.  
  561.   Refer to the chapter entitled "RS232 Signals" for a discussion  of  each  of
  562.   the control and status bits.
  563.  
  564.        SioDTR   : Set, clear, or read the Data Terminal Ready (DTR) bit.
  565.        SioRTS   : Sets, clears, or reads the Request to Send (RTS) line.
  566.        SioModem : Reads the modem status register.
  567.        SioDSR   : Reads the Data Set Ready (DSR) modem status bit.
  568.        SioCTS   : Reads the Clear to Send (CTS) modem status bit.
  569.        SioDCD   : Reads the Data Carrier Detect (DCD) modem status bit.
  570.        SioRI    : Reads the Ring Indicator (RI) modem status bit.
  571.        SioRead  : Reads the contents of the 7 UART registers.
  572.  
  573.  
  574.   2.4 Serial I/O
  575.  
  576.  
  577.   There  are  eight  library  functions  in the serial I/O category. Together,
  578.   these functions give the programmer complete control over serial I/O. Higher
  579.   level functions such as protocols and  smart  modem  communications  can  be
  580.   completely  implemented  in  terms  of these functions. Refer to the example
  581.   code.
  582.  
  583.   SioGetc and SioPutc perform all the actual serial I/O.   SioUnGetc  "ungets"
  584.   the  last  serial  byte  read.  SioRxClear  clears  the  receive queue while
  585.   SioTxClear clears the transmit queue. SioLine can be used to test  for  UART
  586.   errors.   SioRxQue  returns  the  number of bytes in the receive queue while
  587.   SioTxQue returns the number of bytes in the transmit queue.
  588.  
  589.        SioGetc    : Reads the next character from the serial line.
  590.        SioPutc    : Transmit a character over a serial line.
  591.        SioUnGetc  : "Un:gets" (puts back) a specified character.
  592.        SioRxClear : Flush (clears) the receive buffer.
  593.        SioRxQue   : Returns the number of characters in the RX queue.
  594.        SioTxClear : Flush (clears) the transmit buffer.
  595.        SioTxQue   : Returns the number of characters in the TX queue.
  596.        SioLine    : Reads the line status register.
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  PCL4W Users Manual                                                Page 9
  613.   2.5 Error Detection
  614.  
  615.  
  616.   There  are  three  functions  in  the  error  detection  category.  They are
  617.   concerned with detecting or reporting communications errors.  Use  of  these
  618.   functions can make your application significantly more robust.
  619.  
  620.   SioBrkSig can read or  modify  the  UART  break  bit.  This  is  useful  for
  621.   signalling   the   remote  system  that  a  fatal  condition  has  occurred.
  622.   SioLoopBack can be used to test the integrity of your UART.
  623.  
  624.   There is also a file SIOERROR.C which contains the function  SioError  which
  625.   displays  a  error  message  corresponding  to an error code returned from a
  626.   PCL4W function (every PCL4W function returns a code).
  627.  
  628.        SioBrkSig   : Asserts, cancels, or detects the RS232 BREAK  signal.
  629.        SioError    : Displays  error  in  text.
  630.        SioLoopBack : Performs a UART loopback test.
  631.  
  632.  
  633.   2.6 General Support
  634.  
  635.  
  636.   There is one function in the general support category. SioInfo  returns  the
  637.   version  number  of  the  library  and  whether  transmitter  interrupts are
  638.   enabled.
  639.  
  640.        SioInfo      : Returns the library version, memory model, the number of
  641.                       transmitter interrupts, and receiver interrupts.
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  PCL4W Users Manual                                                Page 10
  681.   3.0 Library Overview
  682.  
  683.  
  684.   3.1 Dynamic Link Libraries
  685.  
  686.  
  687.   PCL4W is provided as a dynamic link library (DLL). A DLL is characterized by
  688.   the fact that it need not be loaded until required by an application program
  689.   and that only one copy of the DLL is necessary regardless of the  number  of
  690.   application  programs  that  use it. Contrast this to the traditional static
  691.   library which is bound to each and every application that uses  it  at  link
  692.   time.
  693.  
  694.   Since  PCL4W is a DLL, only one copy of the PCL4W code & data is loaded into
  695.   memory regardless of the number of applications programs that use it.
  696.  
  697.   For example, more than one instance  of  the  test  program  SIMPLE  can  be
  698.   started.   All  copies of SIMPLE can run concurrently as long as each uses a
  699.   different COM port.
  700.  
  701.  
  702.   3.2 DOS Protected Mode Interface
  703.  
  704.  
  705.   Windows itself uses what is known as  the  "DOS  Protected  Mode  Interface"
  706.   (DPMI)  to  control  changing  states  (protected  vs real), controlling the
  707.   interrupt system, etc.  This is necessary because Windows  itself  typically
  708.   runs  in  a  protected  state  and must change to real state in order to use
  709.   MSDOS services.
  710.  
  711.   The  PCL4W  library  uses  this same DPMI mechanism. In particular, the file
  712.   USE_DPMI.ASM contains the necessary functions for using DPMI. The  developer
  713.   should not modify USE_DPMI.ASM in any way.
  714.  
  715.  
  716.   3.3 Memory Models
  717.  
  718.  
  719.   Most windows programs are small or medium memory model programs since  these
  720.   memory models are limited to one data segment.  However, all PCL4W functions
  721.   are FAR functions, so they can be used with any memory model. Thus, there is
  722.   just one PCL4W.DLL and PCL4W.LIB regardless of the memory model used.
  723.  
  724.  
  725.   3.4 Using the Library
  726.  
  727.  
  728.   The  PCL4W has been tested on a Gateway 2000 25 MHZ 80386-DX, a Gateway 2000
  729.   66MHZ 80486-DX2 (all running Windows  3.1),  and  a  Mid-West  Micro  150MHZ
  730.   Pentium running Windows 95.
  731.  
  732.   PCL4W  has  been  testing  with  the  Microsoft Windows SDK compiler, Visual
  733.   C/C++, Borland C/C++, and Watcom C/C++.
  734.  
  735.   Please examine the PCL4W.H file. Note that COM1 is defined as port zero, not
  736.   port  one.   The  user must assume the responsibilty for passing the correct
  737.   information when calling PCL4W functions.
  738.  
  739.   If there are any conflicts between PCL4W  definitions  and  those  in  other
  740.   libraries,  the PCL4W definitions can be changed in the PCL4W.H file and any
  741.   file that uses the definition. There is no change necessary for the  library
  742.   code itself.
  743.  
  744.   If  you  write  an  application  using  the PCL4W library, don't run another
  745.   application that uses the same communications port.
  746.  
  747.  
  748.  PCL4W Users Manual                                                Page 11
  749.   3.5 Using a MAKEFILE
  750.  
  751.  
  752.   Makefiles  originated  on UNIX systems. They are the standard way that C/C++
  753.   programs are constructed in command line environments. Windows programs  can
  754.   be  constructed  with  makefiles  running  DOS  using  command  line Windows
  755.   compilers, such as provide by Borland and Microsoft.
  756.  
  757.   Makefiles are provided for Microsoft and Borland command line compilers.
  758.  
  759.  
  760.   3.6 Using an IDE
  761.  
  762.  
  763.   All windows comilers have an Integrated Development  Environment  (IDE)  for
  764.   building  application programs in the Windows environment. Since there is no
  765.   standard format for IDE project files, file names must be entered  into  the
  766.   IDE  from  the  keyboard.  Each example program has a project text file (eg:
  767.   SIMPLE.PRJ) which contains the list of filenames that must be  entered  into
  768.   the IDE.
  769.  
  770.   The  example  programs  have been build using Microsoft, Borland, and Watcom
  771.   IDEs. Refer to IDE_INFO.DOC for more information on using specfic IDEs.
  772.  
  773.  
  774.   3.7 Making the Library
  775.  
  776.  
  777.   Registered  users  may  wish  to  assemble PCL4W.ASM.  Use the /MX switch in
  778.   order to disable automatic conversion from lower case to upper case.  If the
  779.   /MX switch is not used, then all PCL4W function references in C code must be
  780.   in upper case. To assemble using the Microsoft assembler, use  the  provided
  781.   makefile "PCL4W.MAK". From the DOS command line, type
  782.  
  783.        nmake pcl4w.mak
  784.  
  785.   Two  libraries  are  made, one with transmitter interrupts disabled (PCL4W1)
  786.   and one with transmitter interrupts enabled (PCL4W2). Most users should  use
  787.   the  library  without transmitter interrupts enabled since they require less
  788.   overhead.
  789.  
  790.   To use the PCL4W qlibrary without transmitter interrupts enabled, type
  791.  
  792.        copy pcl4w1.lib pcl4w.lib
  793.        copy pcl4w1.dll pcl4w.dll
  794.  
  795.   To use the PCL4W library with transmitter interrupts enabled, type
  796.  
  797.        copy pcl4w2.lib pcl4w.lib
  798.        copy pcl4w2.dll pcl4w.dll
  799.  
  800.   After creating PCL4W.LIB and PCL4W.DLL, the example programs can be compiled
  801.   and linked. Refer to Chapter 7.0, "Example Programs".
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  PCL4W Users Manual                                                Page 12
  817.   4.0 Talking to Your Modem
  818.  
  819.  
  820.   A  modem  is  used  to  extend  the distance over which you may communicate.
  821.   Without a modem, your RS232 cable is limited to a maximum  of  approximately
  822.   50 feet.  But with a modem, you can communicate literally around the world.
  823.  
  824.  
  825.   4.1 Modem Standards
  826.  
  827.  
  828.   Two modems can communicate over a telephone line only if they are both using
  829.   the  same  signaling frequencies and modulation, which are determined by the
  830.   the modem standards used.  Modem standards can be divided into  three  sets:
  831.   (1) speed, (2) data compression used, and (3) error control.
  832.  
  833.   The  Bell  standards  (103  &  212A)  are  those  of  AT&T.   The CCITT (The
  834.   International Consultative Committee for Telephone and Telegraph)  standards
  835.   are designated as "V. ".
  836.  
  837.  
  838.   Speed
  839.  
  840.  
  841.        Bell 103  :   300 baud
  842.        Bell 212A :  1200 baud
  843.        V.21      :   300 baud
  844.        V.22bis   :  1200 & 2400 baud
  845.        V.32      :  4800 & 9600 baud
  846.        V.32bis   :  4800, 7200, 9600, 12000, and 14400 baud
  847.  
  848.  
  849.   Data Compression
  850.  
  851.  
  852.        MNP 5     :  Microcom Networking Protocol (proprietary).
  853.        V.42bis   :  International data compression standard.
  854.  
  855.  
  856.   Error Control
  857.  
  858.  
  859.        MNP 2,3,4 :  Three level error correction (public domain).
  860.        V.42      :  International error correction standard.
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  PCL4W Users Manual                                                Page 13
  885.   4.2 Flow Control
  886.  
  887.  
  888.   With  modems  using data compression, the modem to modem connection will run
  889.   at various speeds depending on the quality of the  line.   The  computer  to
  890.   modem  connection  will be at a fixed baud rate. Therefore, a protocol (flow
  891.   control) is necessary to synchronize the data flow between a modem  and  the
  892.   computer  to  which  it  is  connected.   Refer  to  your  modem  manual for
  893.   information on flow control protocols supported.
  894.  
  895.   Two flow control protocols are used by most all modems  which  require  flow
  896.   control.  Software  flow  control  is called "XON/XOFF" (other software flow
  897.   control character pairs are defined but operate the same  as  XON/XOFF)  and
  898.   hardware  flow  control is called "RTS/CTS".  Most modems which require flow
  899.   control enable hardware flow control by default.
  900.  
  901.   In XON/XOFF (software) flow control, the computer suspends transmitting data
  902.   if it receives a XOFF character (13  hex)  from  the  modem,  and  continues
  903.   transmitting  when  it  receives  a XON character (11 hex).  Similiarly, the
  904.   computer can signal the modem not to send any more data  by  transmitting  a
  905.   XOFF  to  it,  and  can tell the modem to continue transmission be sending a
  906.   XON.
  907.  
  908.   In RTS/CTS (hardware) flow control, the RTS line is used by the computer  to
  909.   signal  the  modem  ,  while the CTS line is used by the modem to signal the
  910.   computer.  The RTS line is set OFF by the computer  to  tell  the  modem  to
  911.   suspend  transmission,  and  set  to  ON  to  tell  the  modem  to  continue
  912.   transmission.  The CTS line is set to OFF by the modem to tell the  computer
  913.   to  stop  transmitting,  and  set  to  ON  to  tell the computer to continue
  914.   transmitting.
  915.  
  916.   Given the choice, always choose hardware flow  control  over  software  flow
  917.   control  so  that  all  data  transmission is transparent.  If hardware flow
  918.   control is not the default (which it almost always is),  you  should  modify
  919.   your modem initialization string to turn hardware flow control on.
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  PCL4W Users Manual                                                Page 14
  953.   4.3 MODEM I/O (MIO)
  954.  
  955.   4.3.1 MIO Introduction
  956.  
  957.   The file MIO.H contains declarations for using the  Modem  I/O  DLL.   These
  958.   functions  ease  communicating  with  modems  using  AT commands.  The LOGIN
  959.   example program code has examples of using the MIO functions.
  960.  
  961.   The Windows "operating system" is what is called "cooperative multitasking".
  962.   This  means  that  the  executing  Windows  task  must voluntarily "give up"
  963.   control before another Windows task (or Windows itself) can execute.
  964.  
  965.   The difficulty  is  how  to  wait  for  a  number  of  seconds  while  still
  966.   relinquishing control periodically before the wait is up. One solution is by
  967.   making  functions that need to wait (such as the MIO functions) into "state"
  968.   machines. A function is broken down into parts called states, and control is
  969.   returned to Windows between executing each state.
  970.  
  971.   For example, to send the string "ATDT1,205,880,9748" to the modem  with  one
  972.   tenth second delay between transmitted characters, the following sequence is
  973.   used:
  974.  
  975.   (1) Send the string to the MIO driver by executing:
  976.  
  977.   Code = mioSendTo(Port,100,"!ATDT1,205,880,9748")
  978.  
  979.   The '!' characters are converted to carriage returns.  The  text  string  is
  980.   copied into the driver's data area.
  981.  
  982.   (2)  Call mioDriver (typically based on a timer) until MIO_IDLE is returned.
  983.   Each time mioDriver is called, it will send another character to  the  modem
  984.   provided  the  required  delay  (since  the previous character was sent) has
  985.   passed.  If the delay has not passed, the driver simply returns MIO_RUNNING,
  986.   but without actually sending a character to the modem.  Once all  characters
  987.   have been sent, mioDriver will return MIO_IDLE, indicating it is done and is
  988.   ready to accept another function.
  989.  
  990.   mioDriver  will return MIO_RUNNING if it is still processing.  Anything else
  991.   received indicates that it is still processing and the returned value  is  a
  992.   character from the modem that can be displayed if wanted.
  993.  
  994.   (3) Once mioDriver returns MIO_IDLE, call mioResult to get the result of the
  995.   mioSendTo call.
  996.  
  997.   The above is rather straight forward in practice.  See the LOGIN application
  998.   for an example of its use.
  999.  
  1000.  
  1001.   4.3.2 MIO Functions
  1002.  
  1003.   4.3.2.1 mioDriver
  1004.  
  1005.   Syntax: int mioDriver(int Port)
  1006.  
  1007.   mioDriver  executes  the  next  state of any previously started MIO function
  1008.   such as mioSendTo, mioWaitFor, and mioQuiet. It returns:
  1009.  
  1010.   MIO_IDLE    : if the driver is ready for the next mioSendTo, mioWaitFor, or
  1011.                 mioQuiet.
  1012.   MIO_RUNNING : if the driver is not idle.
  1013.   <otherwise> : if the driver is not idle,  and  the  returned  character  was
  1014.                 received from the modem.
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  PCL4W Users Manual                                                Page 15
  1021.   4.3.2.2 mioBreak
  1022.  
  1023.  
  1024.   Forces the MIO driver to the IDLE state, abandoning any work in progress.
  1025.  
  1026.  
  1027.   4.3.2.3 mioSendTo
  1028.  
  1029.  
  1030.   Syntax:  int mioSendTo(int Port, long Pace, char *String)
  1031.  
  1032.   The mioSendTo function sends the characters in the string 'Text'  to  serial
  1033.   output. There is a delay of 'Pace' milliseconds between characters.
  1034.  
  1035.  
  1036.   4.3.2.4 mioWaitFor
  1037.  
  1038.  
  1039.   Syntax: int mioWaitFor(int Port, long Wait, int Case, char *String)
  1040.  
  1041.   The  mioWaitFor  function  waits for characters from serial input that match
  1042.   the string 'Text'. A total of 'Wait' milliseconds are allowed before  timing
  1043.   out  and  returning  FALSE (0).  If the 'Case' flag is TRUE, then the string
  1044.   comparison is NOT case sensitive.
  1045.  
  1046.   For example, to wait up to one minute for "CONNECT", "NO CARRIER", or "BUSY"
  1047.   from the modem after dialing a number (on COM1):
  1048.  
  1049.   Code = mioWaitFor(COM1,60000,1,"CONNECT|NO CARRIER|BUSY")
  1050.  
  1051.   The function mioDriver() must be called until MIO_IDLE  is  returned.   Then
  1052.   mioResult()  is  called  to  get the result of the mioWaitFor.  A value of 0
  1053.   indicates  that  neither "CONNECT", "BUSY", nor "NO CARRIER" was received. A
  1054.   non-zero value indicates that one of the three sub-strings was received.   A
  1055.   ASC("0")  is  returned  if  "CONNECT"  was seen, ASC("1") is returned if "NO
  1056.   CARRIER" was seen, and ASC("2") is returned if "BUSY" was seen.
  1057.  
  1058.  
  1059.   4.3.2.5 mioQuiet
  1060.  
  1061.  
  1062.   Syntax: int mioQuiet(int Port,long Wait)
  1063.  
  1064.   The mioQuiet function waits for continuous quiet [no incoming  serial  data]
  1065.   of  'Wait'  milliseconds  before  returning.   Any  incoming character while
  1066.   mioQuiet us running is flushed.
  1067.  
  1068.  
  1069.   4.3.3 MIO Summary
  1070.  
  1071.  
  1072.   mioDriver   : Allows  the  execution  of  mioSendTo,  mioWaitFor, or
  1073.                 mioQuiet once they have been  started.  Returns  MIO_IDLE
  1074.                 (defined in MIO.H) if ready not running,   MIO_RUNNING if
  1075.                 running,  and anything else is a character from the modem
  1076.                 that can be displayed if wanted.
  1077.   mioBreak    : Forces the MIO driver to IDLE state.
  1078.   mioSendTo   : Sends string (including control chars) to the modem.
  1079.   mioWaitFor  : Waits for a particular string from the modem, passing
  1080.                 all else through.
  1081.   mioQuiet    : Waits for continuous quiet of specified duration.
  1082.   mioBreak    : Breaks further modem I/O activity.
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  PCL4W Users Manual                                                Page 16
  1089.   4.4 Modem Initialization
  1090.  
  1091.  
  1092.   If your application uses a modem (as opposed to using a null  modem  cable),
  1093.   then  you should always send an initialization string to your modem if it is
  1094.   a programmable modem such as those made by  Hayes.   Communication  programs
  1095.   such as PROCOMM and TELIX always send such a string automatically as soon as
  1096.   they start up.
  1097.  
  1098.   The particular initialization string depends on the make of your modem.  For
  1099.   Hayes  and  Hayes  AT  command  set  compatible modems, the following string
  1100.   (followed by a carriage return) should work:
  1101.  
  1102.        AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
  1103.  
  1104.   Refer to your Modem User's Guide for a full discussion of these commands.  A
  1105.   brief description is as follows:
  1106.  
  1107.        AT     Modem attention command.
  1108.        E1     Modem will echo what you send to it.
  1109.        S7=60  Wait 60 seconds for carrier and/or dial tone.
  1110.        S11=60 Use 60 milliseconds for tone dialing duration & spacing.
  1111.        V1     Display result code as words (not numbers).
  1112.        X1     Use the extended result message (CONNECT XXXX) set.
  1113.        Q0     Modem returns result codes.
  1114.        S0=0   Do not answer RING.
  1115.  
  1116.   If  your application will answer incoming calls, then set the S0 register to
  1117.   the ring on which to automatically answer.
  1118.  
  1119.   If you send the above codes by using SioPutc (as opposed to typing them from
  1120.   the keyboard), then follow these guidelines:
  1121.  
  1122.   (1) Send an initial carriage return before the initialization string.
  1123.  
  1124.   (2) Pause at least 150 milliseconds after each character sent as your  modem
  1125.   needs the time to perform its own internal processing. Pause a little longer
  1126.   if your modem is not accepting your initialization string.
  1127.  
  1128.   (3)  Pause  one  and a half seconds after sending any initialization command
  1129.   such as ATZ or AT&F since your modem must do quite a bit of processing.
  1130.  
  1131.   If you experience any problems in initializing your Hayes modem, you  should
  1132.   first reset it to factory settings by sending:
  1133.  
  1134.        AT&F
  1135.  
  1136.   Refer to the LOGIN program (function SendToModem in the file MODEM_IO.C)  for
  1137.   an example of sending an initialization string to a Hayes compatible modem.
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  PCL4W Users Manual                                                Page 17
  1157.   5.0 Problems
  1158.  
  1159.  
  1160.   If  you  cannot  get your application to run properly, first compile and run
  1161.   the terminal emulator program SIMPLE provided  on  your  distribution  disk.
  1162.   Test  SIMPLE  by  connecting  two  computers  with  a null modem cable or by
  1163.   commanding a Hayes AT command set compatible modem.
  1164.  
  1165.   Once  SIMPLE  runs, compile and run the SELFTEST program.  This program will
  1166.   test your serial ports functionality.
  1167.  
  1168.   If your application does not run but  SIMPLE  and  SELFTEST  run  correctly,
  1169.   then  you  have  most likely made a programming mistake in your application.
  1170.   MarshallSoft Computing cannot debug your application,  especially  over  the
  1171.   telephone!  However,  consider  each  of the following when searching for an
  1172.   error in your application.
  1173.  
  1174.   1.  Have you included the file PCL4W.H in your application ?
  1175.  
  1176.   2.  Is your receive buffer large enough ? If you are using 1K data blocks in
  1177.   YMODEM,  then  your  receive  buffer should be at least 1K (2K if baud rates
  1178.   above 19200 are to be used).
  1179.  
  1180.   3.  Have you selected too high a baud rate? Windows can multitask many tasks
  1181.   at once. You may have to lower your baud rate (or get 16550 UARTS).
  1182.  
  1183.   4.  If you are running two COM ports simultaneously, are you using separate
  1184.   receive and transmits buffers ? (you should).
  1185.  
  1186.   5.  Did SioReset return a zero value ?  If not, then you must call  SioReset
  1187.   again. See LOGIN.C for an example.
  1188.  
  1189.   6.   Did  you  send the proper initialization string to your modem ? Did you
  1190.   set DTR and RTS ? (you should).
  1191.  
  1192.   7.  Do you have more than one COM1 port?  For example, if you  have  a  COM1
  1193.   port  on  your  motherboard, you cannot add another COM1 port or modem board
  1194.   that uses COM1 without first disabling the COM1 on the motherboard.
  1195.  
  1196.   8.   Is  your  IRQ set correctly? If you can transmit data but can't receive
  1197.   using the PCL4W library with transmitter interrupts disabled (PCL4W2),  then
  1198.   this usually means that interrupts are not working.
  1199.  
  1200.   9. If -19 is returned from SioReset, this means that  you  have  not  called
  1201.   PostMainHandle() from within your code first. See example in SIMPLE.C.
  1202.  
  1203.   We recommend the following steps if you believe that you have  discovered  a
  1204.   bug  in  the  library:  (1)  Create  the  smallest,  simpliest  test program
  1205.   possible that demonstrates the problem.  (2)  Document  your  exact  machine
  1206.   configuration  and  what error the test program  demonstrates.   (3)  Upload
  1207.   the example source to our user support BBS, email it or mail us a disk.
  1208.  
  1209.   If  the  problem can be solved with an easy work-around, we will publish the
  1210.   work-around.  If the problem requires a modification to the library, we will
  1211.   make the change and make the modified library  available  to  our  customers
  1212.   without charge.
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  PCL4W Users Manual                                                Page 18
  1225.   6.0 Serial Communications
  1226.  
  1227.   6.1 Communications Basics
  1228.  
  1229.  
  1230.   The  heart  of  serial  communications  is  the UART (Universal Asynchronous
  1231.   Receiver Transmitter).  The IBM  PC/XT/AT  and  compatibles  use  the  8250,
  1232.   16450, or the 16550 UART.  The purpose of the UART is:
  1233.  
  1234.   (1) To convert bytes from the CPU (Central Processing Unit), into  a  serial
  1235.   format  by  adding  the  necessary start, stop, and parity bits to each byte
  1236.   before transmission, and to then transmit each bit at the correct baud rate.
  1237.  
  1238.   (2) To convert the incoming stream (at a specified baud rate) of serial bits
  1239.   into bytes by removing the start, stop, and parity bits  before  being  made
  1240.   available to the CPU.
  1241.  
  1242.   The  UART  is part of the serial interface circuitry which allows the CPU to
  1243.   send and receive signals over the RS232 lines. This  can  be  diagrammed  as
  1244.   follows:
  1245.  
  1246.  
  1247.  
  1248.                         Serial Interface
  1249.                      +-------------------+
  1250.                      |                   |
  1251.   +-----+  Data Bus  |     +------+      |    RS232 Signals
  1252.   | CPU +------------+     | UART |      +----------------*
  1253.   +-----+            |     +------+      |
  1254.                      |                   |
  1255.                      +-------------------+
  1256.  
  1257.  
  1258.  
  1259.   The  8250/16450/16550  UART  is  capable  of  operating in one of two modes,
  1260.   "polled" and "interrupt driven".  The serial communications functions in the
  1261.   BIOS uses the polled method.  In this approach, the CPU is  typically  in  a
  1262.   loop  asking  the  UART  over  and over again if it has a byte ready. If its
  1263.   does, the polling code returns the byte.  But, if the  next  byte  comes  in
  1264.   before the polling code is executing again, then that byte is lost.
  1265.  
  1266.   In the interrupt driven approach (used by PCL4W), when a byte is received by
  1267.   the  UART,  an  "Interrupt  Service  Routine" (ISR) is executed immediately,
  1268.   suspending temporarily whatever else is executing. The ISR  then  moves  the
  1269.   byte to a buffer so that your application program can later read it.
  1270.  
  1271.   If transmitter interrupts are enabled, then  bytes  are  queued  up  waiting
  1272.   transmission.   When  a  byte  is  moved  from  the UART transmitter holding
  1273.   register to the UART transmitter shift register, an interrupt  is  generated
  1274.   and  the  next  byte is taken from the library transmitter buffer by the ISR
  1275.   and written to the UART holding register.
  1276.  
  1277.   Up to 16 bytes can be taken from the transmitter buffer while processing one
  1278.   transmitter  interrupt  if an 16550 UART is used. The 16550 UART is strongly
  1279.   recommended for computers doing serial communications under Windows.
  1280.  
  1281.   Refer to Sections  6.6  and  6.7  entitled  "RS232  Signals"  and  "National
  1282.   INS8250,   INS16450,   and   INS16550   UARTs",   respectively  for  further
  1283.   information on these topics.
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  PCL4W Users Manual                                                Page 19
  1293.   6.2 Standard Port Addresses
  1294.  
  1295.  
  1296.   There  are  a  few  things to know about how serial communications ports are
  1297.   used by IBM PC/XT/AT and compatible computers.  The  standard  IBM  PC/XT/AT
  1298.   configuration values are as follows:
  1299.  
  1300.         Port     Reg Base   IRQ Line   Vector
  1301.         COM1        3F8H         4        12
  1302.         COM2        2F8H         3        11
  1303.         COM3        3E8H         4        12
  1304.         COM4        2E8H         3        11
  1305.  
  1306.   (Refer  to  your  DigiBoard  manual  for  DigiBoard addresses, and your BOCA
  1307.   manual for BOCA board addresses).
  1308.  
  1309.   PCL4W  assumes the above values.  If necessary, the UART base address can be
  1310.   changed by SioUART, and IRQ lines can be re-assigned  by  SioIRQ.   Remember
  1311.   that  each  port to be used concurrently must have a unique IRQ line.  Refer
  1312.   to the PCL4W Reference Manual for specific details.
  1313.  
  1314.   When installing new  communications  cards,  the  following  guidelines  are
  1315.   recommended:
  1316.  
  1317.   (1)  Be  sure to read the documentation for the hardware you are installing.
  1318.   Pay special attention to UART base addresses and IRQ lines, particularly  if
  1319.   trying to set up a non-standard configuration.
  1320.  
  1321.   (2)  If  you  have  a  choice in base addresses and IRQ lines, always choose
  1322.   standard values as defined above.
  1323.  
  1324.   (3) The first port should be COM1, the second COM2, etc.
  1325.  
  1326.   (4)  Use SioUART to zero all unused ports (for example, call SioUART(COM4,0)
  1327.   if there is no COM4 port installed).
  1328.  
  1329.   (5) Be carefull not to configure two ports for the  same  address.  This  is
  1330.   easier to do than you may believe.
  1331.  
  1332.   (6)  Choose  an  external  modem over an internal one.  It is much easier to
  1333.   debug problems with an external modem than an internal one.
  1334.  
  1335.   (7) Select hardware flow control (RTS/CTS) if flow control is  required  and
  1336.   hardware flow control is not the default.
  1337.  
  1338.   (8)  Always  test your port as soon as it is installed. Try several programs
  1339.   that use the communications ports.
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  PCL4W Users Manual                                                Page 20
  1361.   6.3 Running 3 or 4 Ports Concurrently
  1362.  
  1363.  
  1364.   PCL4W supports up to 4 serial ports running concurrently (more if you have a
  1365.   DigiBoard or BOCA board).  One free interrupt for  each  port  is  required.
  1366.   Refer to the next section if you have a DigiBoard or BOCA board.
  1367.  
  1368.   Interrupts IRQ4 and IRQ3 are dedicated to  the  communications  ports  in  a
  1369.   standard  IBM  PC/XT/AT configuration.  IRQ4 is shared between COM1 and COM3
  1370.   while IRQ3 is shared between COM2 and COM4.  This means that you can run two
  1371.   ports simultaneously provided that they don't share an interrupt.
  1372.  
  1373.   Suppose that you wish to run 3 ports simultaneously. To begin, you must have
  1374.   3 serial UARTs installed on your computer.  Assume,  for  purposes  of  this
  1375.   discussion,  that  COM1  is installed on your motherboard, and that you have
  1376.   purchased a new 2 port serial communications board.
  1377.  
  1378.   You should be able to configure the first serial board port as  COM2,  which
  1379.   uses IRQ3.  Refer to the manual that came with your serial board.
  1380.  
  1381.   In  order  to  run the third serial port concurrently with the first two, an
  1382.   unused interrupt must be found.  If your serial card can use only  IRQ3  and
  1383.   IRQ4,  then there is no way to run a third line since IRQ4 and IRQ3 are used
  1384.   for COM1 and COM2.
  1385.  
  1386.   However, many serial cards can use other IRQs, typically IRQ2 through  IRQ7.
  1387.   Since  IRQ5  is  normally  used  for  a  second  printer  port, it is a good
  1388.   candidate for COM3. To use IRQ5 for the third serial port,  first  set  your
  1389.   serial card to use IRQ5 for COM3 (refer to your serial card manual) and then
  1390.   add the following line to your applications code before calling SioReset:
  1391.  
  1392.        SioIRQ(COM3,IRQ5);
  1393.  
  1394.   Don't  forget  to  disable  any device that might use IRQ5, such as a second
  1395.   printer port or a music card.   Unfortunately,  there  is  no  easy  way  to
  1396.   determine  that  you have no conflicts until you actually attempt to use the
  1397.   IRQ. If there are conflicts, your system will probably  hang  and  you  will
  1398.   have to reboot.
  1399.  
  1400.   To  run  a  fourth  serial  port,  another  free IRQ must be found.  On some
  1401.   systems, IRQ7 can be used. You must first disable IRQ7 on your parallel port
  1402.   card first (your printer doesn't need an IRQ). To use IRQ7  for  the  fourth
  1403.   serial port, first set your serial card to use IRQ7 for COM4 and then add:
  1404.  
  1405.        SioIRQ(COM4,IRQ7);
  1406.  
  1407.   To  summarize,  your  serial  card must be able to generate the correct IRQ,
  1408.   which is not already being used. Refer to the entry for the SioIRQ  function
  1409.   in the PCL4W Reference Manual.
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  PCL4W Users Manual                                                Page 21
  1429.   6.4 Using Multiport Cards
  1430.  
  1431.  
  1432.   The  PCL4W  library supports the dumb Digiboard (PC/4 and PC/8) and the dumb
  1433.   BOCA board (BB1004, BB1008, and BB2016).   Most  multiport  boards  will  be
  1434.   compatible  with either the DigiBoard (the status register contains the port
  1435.   number), or the BOCA board (the status register is bit mapped).
  1436.  
  1437.   6.4.1 The DigiBoard
  1438.  
  1439.   In order to use the DigiBoard, (not the Intelligent Digiboards such  as  the
  1440.   PC/Xe  and  PC/Xi) you must configure PCL4W using the SioPorts(), SioUART(),
  1441.   and SioIRQ() functions.
  1442.  
  1443.   Your  PCs  ports  must be partitioned into "standard" PC ports and dumb card
  1444.   ports.  Remember that standard PC ports cannot share IRQs like the DigiBoard
  1445.   (or BOCA board) can. If you are using IRQ4 and IRQ3 for  standard  PC  ports
  1446.   COM1  and  COM2, then you cannot use either for DigiBoard ports (try IRQ5 or
  1447.   IRQ7).
  1448.  
  1449.   Suppose that COM1 through COM2 are standard PC ports (using IRQ4  and  IRQ3)
  1450.   and  you  have  installed  a  PC/8  DigiBoard  that you wish to use for COM3
  1451.   through COM10 using interrupt line IRQ5.  You choose to use the  recommended
  1452.   DigiBoard UART addresses starting at 0x100:
  1453.  
  1454.      SioPorts(10,COM3,0x140,DIGIBOARD);/* COM3 = 1st DigiBoard port */
  1455.      Address  = 0x100;                 /* 1st DigiBoard UART address */
  1456.      for(Port=COM3;Port<=COM10;Port++) /* look at each port    */
  1457.        {SioUART(Port,Address);         /* set the UART address */
  1458.         Address += 8;                  /* compute next address */
  1459.         SioIRQ(Port,IRQ5);             /* set the DigiBoard IRQ */
  1460.        }
  1461.  
  1462.   The DigiBoard uses 0x140 for the status address for odd interrupts and 0x141
  1463.   for even interrupts.
  1464.  
  1465.   Digiboard  may  be  contacted  at  6400 Flying Cloud Drive, Eden Prairie, MN
  1466.   55344.  Telephone 612-943-9020 or FAX 612-943-5398.
  1467.  
  1468.  
  1469.   6.4.2 The BOCA Board
  1470.  
  1471.   In  order  to  use  the dumb BOCA Boards, you must configure PCL4W using the
  1472.   SioPorts(), SioUART(), and SioIRQ() functions.
  1473.  
  1474.   For example, to configure the BOCA BB2016 to use COM1 to  COM16,  with  base
  1475.   addresses starting at 0x100 and IRQ5:
  1476.  
  1477.      SioPorts(16,COM1,0x107,BOCABOARD);/* COM3 = 1st BOCA board port */
  1478.      Address = 0x100;                  /* 1st BOCA UART address */
  1479.      for(Port=COM1;Port<=COM16;Port++) /* look at each port    */
  1480.        {SioUART(Port,Address);         /* set the UART address */
  1481.         Address += 8;                  /* compute next address */
  1482.         SioIRQ(Port,IRQ5);             /* set the BOCA IRQ */
  1483.        }
  1484.  
  1485.   BOCA may be contacted at BOCA Research, Inc., 6413  Congress  Avenue,  Suite
  1486.   130, Boca Raton, FL 33487.  Phone 407-241-8088, FAX 407-997-0918.
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  PCL4W Users Manual                                                Page 22
  1497.   6.5 Transmitter Interrupts
  1498.  
  1499.  
  1500.   Transmitter interrupts are supported by the library.  Separate libraries are
  1501.   provided, one with transmitter interrupts enabled  and  one  without.   When
  1502.   transmitter  interrupts  are  NOT  enabled, the following logic occurs every
  1503.   time you call SioPutc():
  1504.  
  1505.    1. Wait for transmit buffer to become empty. The transmit  buffer  may  not
  1506.   be empty if the previous transmit is not completed (the UART breaks down the
  1507.   byte  &  sends  1  bit at a time). 2. When the transmit buffer is empty, the
  1508.   byte from the SioPutc() call is loaded into the transmit buffer and  control
  1509.   is returned to the caller.
  1510.  
  1511.   Note that you can not write to the UART any faster the the UART baud rate.
  1512.  
  1513.   When transmitter interrupts are enabled, the byte from SioPutc() is put into
  1514.   a previously prepared (by SioTxQue) transmitter queue. The interrupt service
  1515.   routine fetches bytes from this queue as soon as the previous byte has  been
  1516.   sent.
  1517.  
  1518.   While you can now call SioPutc() faster than the baud rate, bytes are  still
  1519.   transmitted at the given baud rate.
  1520.  
  1521.   The   above   sounds   like  transmitter  interrupts  are  the  way  to  go.
  1522.   Unfortunately, this is usually NOT the case.  Most applications will perform
  1523.   better if transmitter interrupts are NOT enabled.
  1524.  
  1525.   The reason is that transmitter interrupts double the amount of code  in  the
  1526.   time  critical interrupt service routine.  While the library is processing a
  1527.   transmitter interrupt (which can take a while), incoming bytes  can  not  be
  1528.   processed.  What this means is that a given machine can run at a higher baud
  1529.   rate without transmitter interrupts. This problem is compounded when running
  1530.   multiple ports simultaniously.
  1531.  
  1532.   However,  there are a few application areas where transmitter interrupts are
  1533.   preferable.  If your application will be  transmitting  blocks  of  data  at
  1534.   fairly slow baud rates you might profit from enabling transmitter interrupts
  1535.   provided  that there is something else for the processor to do (which is NOT
  1536.   the case in most protocols).
  1537.  
  1538.   However,  if  you are using 16550 UARTS (which have 16 byte on-chip transmit
  1539.   and receive buffers rather that the 1 byte buffers on  the  8250  and  16450
  1540.   UARTS),  you  may  want  to  use the library version with interrupts enabled
  1541.   provided that you enable the 16550 UART with the SioFIFO() function.
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  PCL4W Users Manual                                                Page 23
  1565.   6.6 RS-232 Signals
  1566.  
  1567.  
  1568.   RS-232 is the name of the serial data interface  standard  used  to  connect
  1569.   computers  to modems.  Most IBM compatible computers are built with at least
  1570.   one serial port and use either DB9 (9 pin) or DB25 (25 pin) connectors.
  1571.  
  1572.   A summary of these pins and  their  function  follows.   For  more  detailed
  1573.   information, refer to one of the many books dealing with RS-232 interfacing.
  1574.  
  1575.   Signal Ground Pin 7 (DB25), Pin 5 (DB9)
  1576.  
  1577.   The  SG  line  is  used  as  the  common  signal  ground, and must always be
  1578.   connected.
  1579.  
  1580.   Transmit Data Pin 2 (DB25), Pin 3 (DB9)
  1581.  
  1582.   The TX line is used to carry data from the computer to the modem.
  1583.  
  1584.   Receive Data Pin 3 (DB25), Pin 2 (DB9)
  1585.  
  1586.   The RX line is used to carry data from the modem to the computer.
  1587.  
  1588.   Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9)
  1589.  
  1590.   The DTR line is used by the computer to signal the modem that it  is  ready.
  1591.   DTR should be set high when talking to a modem.
  1592.  
  1593.   Data Set Ready Pin 6 (DB25), Pin 6 (DB9)
  1594.  
  1595.   The DSR line is used by the modem to signal the computer that it is ready.
  1596.  
  1597.   Request to Send Pin 4 (DB25), Pin 7 (DB9)
  1598.  
  1599.   The  RTS  line  is used to "turn the line around" in half duplex modems, and
  1600.   for hardware flow control in most modems that require flow control.  RTS  is
  1601.   controlled by the computer and read by the serial device (modem).
  1602.  
  1603.   Clear to Send Pin 5 (DB25), Pin 8 (DB9)
  1604.  
  1605.   The  CTS  line  is used to "turn the line around" in half duplex modems, and
  1606.   for hardware flow control in most modems that require flow control.  CTS  is
  1607.   controlled by the serial device (modem) and read by the computer.
  1608.  
  1609.   Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9)
  1610.  
  1611.   The DCD line is used by the modem to signal the computer that a data carrier
  1612.   signal is present.
  1613.  
  1614.   Ring Indicator Pin 22 (DB25), Pin 9 (DB9)
  1615.  
  1616.   The RI line is asserted when a 'ring' occurs.
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  PCL4W Users Manual                                                Page 24
  1633.   6.7 National INS8250, INS16450, and INS16550 UARTs
  1634.  
  1635.  
  1636.   The  Personal  Communications  Library  is  based  on  the standard National
  1637.   INS8250, INS16450, and INS16550 UARTs. The 8250 was the original  UART  used
  1638.   in  the IBM PC, whereas the 16450 is a faster version found on most 286 & up
  1639.   machines. The 16550 contains a 16 byte FIFO to further reduce communications
  1640.   overhead. These UARTs consists of 8 register ports as follows:
  1641.  
  1642.   Offset R/W Register
  1643.      0   R/W    Receiver  (read)  /  Transmitter  (write)
  1644.      1   R/W    Interrupt Enable (read)
  1645.      2   R      Interrupt Identification
  1646.      2   W      FIFO control (INS16550 only)
  1647.      3   R/W    Data Format (Line Control)
  1648.      4   R/W    RS-232 (Modem) Control
  1649.      5   R/W    Line Status
  1650.      6   R/W    RS-232 (Modem) Status
  1651.      7   R/W    Not used.
  1652.  
  1653.   For  the  standard  PC  ports  (not DigiBoard ports), the UART registers are
  1654.   based at 3F8h (COM1), 2F8h (COM2), 3E8h (COM3), and 2E8h (COM4).   COM1  and
  1655.   COM3  share  interrupt  request  line IRQ4 while COM2 and COM4 share request
  1656.   line IRQ3.  This means that  COM1  and  COM3  can't  be  used  concurrently.
  1657.   Similarly for COM2 and COM4.
  1658.  
  1659.   However,  standard PC ports may be re-configured to use other UART addresses
  1660.   and IRQ assignments.  Refer  to  the  SioPorts(),  SioUART(),  and  SioIRQ()
  1661.   functions.
  1662.  
  1663.   If  you  have  a  DigiBoard PC/4 (or PC/8) installed, you will have 4 (or 8)
  1664.   additional ports using INS16450 or INS16550 UARTS.   The  default  DigiBoard
  1665.   ports  are  located  at 100h, 108h, 110h & 118h for the PC/4 continuing with
  1666.   120h 128h, 130h & 138h for the PC/8. IRQ3 is the default for all ports.
  1667.  
  1668.   Four sources of interrupts  are  possible  with  the  8250  and  16550:  (1)
  1669.   receiver error or BREAK, (2) receiver data ready, (3) ready to transmit, and
  1670.   (4)  RS232  input.   These  four  sources  of  interrupts  are summarized as
  1671.   follows:
  1672.  
  1673.        Source of Interrupt        Action Required to Clear
  1674.        Receiver error or BREAK.   Read Line Status register.
  1675.        Receiver data.             Read data from data register.
  1676.        Transmitter Buffer Empty.  Write to data register or read IID reg.
  1677.        RS232 Input.               Read Modem Status register.
  1678.  
  1679.   If  you are not familiar with UARTS, several good books are available. Refer
  1680.   to  Chapter  6.0,  Serial  Communications   chapter   for   recommendations.
  1681.   Although  a knowledge of the 8250/16450/16550 is not necessary to use PCL4W,
  1682.   a general knowledge of the theory of asynchronous serial  communications  is
  1683.   helpful.
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  PCL4W Users Manual                                                Page 25
  1701.   6.8 Register Summary
  1702.  
  1703.  
  1704.   REG 0 : Data Register
  1705.  
  1706.   Reading from the data register fetches the  next  input  byte,  once  it  is
  1707.   ready.   Writing  to the data register transmits the byte written to it over
  1708.   the serial line.
  1709.  
  1710.   REG 1 : Interrupt Enable 
  1711.  
  1712.   The Interrupt Enable register enables each of four types of interrupts  when
  1713.   the appropriate bit is set to a one.
  1714.  
  1715.        bit 3 :  Enable interrupt  on  RS232  input.
  1716.        bit 2 :  Enable interrupt on receiver error or break.
  1717.        bit 1 :  Enable interrupt on transmitter buffer empty (TBE).
  1718.        bit 0 :  Enable interrupt on received data (RxRDY).
  1719.  
  1720.   REG 2 : Interrupt Identification (IID)
  1721.  
  1722.   Reading the Interrupt Identification (read only) register once an  interrupt
  1723.   has occurred identifies the interrupt as follows:
  1724.  
  1725.        Bit 2  Bit 1  Bit 0  Priority   Interrupt
  1726.          0     0      1      none      none
  1727.          1     1      0      0         (high) Serialization or break.
  1728.          1     0      0      1         Received data.
  1729.          0     1      0      2         Transmitter Buffer Empty.
  1730.          0     0      0      3         (low) RS232 Input.
  1731.  
  1732.   In  the  INS16650,  REG  2  (write  only) is also the FIFO control register.
  1733.   Writing bits 6 & 7 will set the FIFO trigger level (number of bytes received
  1734.   before an interrupt is generated).
  1735.  
  1736.         Bit 7  Bit 6   Trigger             Bit 7  Bit 6   Trigger
  1737.           0      0      1 byte               1      0     8 bytes
  1738.           0      1      4 bytes              1      1     14 bytes
  1739.  
  1740.   REG 3 : Line Control
  1741.  
  1742.   RS232 line parameters are selected by writing to this register.
  1743.  
  1744.        bit 7   : DLAB = 0
  1745.        bit 6   : BREAK on(1), off(0).
  1746.        bits 5-3: Parity None(000),ODD(001),EVEN(011),MARK(101),SPACE(111)
  1747.        bit 2   : One stop bit(0), two stop bits(1).
  1748.        bits 1-0: Data bits = 5 (00), 6(01), 7(10), 8(11).
  1749.  
  1750.   When  the Divisor Latch Access Bit (DLAB) is 1, registers 0 and 1 become the
  1751.   LS and MS bytes of the Baud Rate Divisor registers.
  1752.  
  1753.        Baud   Divisor      Baud  Divisor      Baud  Divisor
  1754.         300    0180        4800   0018       38400   0003
  1755.        1200    0060        9600   000C       57600   0002
  1756.        2400    0030       19200   0006      115200   0001
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  PCL4W Users Manual                                                Page 26
  1769.   REG 4 : Modem Control
  1770.  
  1771.   RTS, DTR, loopback testing, and  General  Purpose  Outputs  #1  and  #2  are
  1772.   controlled by the Modem Control register as follows:
  1773.  
  1774.        bit 4 : Enable local loopback.
  1775.        bit 3 : Enable GP02. Necessary for 8250 interrupts.
  1776.        bit 2 : Enable GP01.
  1777.        bit 1 : Set / clear RTS.
  1778.        bit 0 : Set / clear DTR.
  1779.  
  1780.   REG 5 : Line Status
  1781.  
  1782.   Reading  the  Line Status register provides status information as follows (1
  1783.   for TRUE, 0 for FALSE) :
  1784.  
  1785.        bit 6 : Transmitter Empty.
  1786.        bit 5 : Transmitter Buffer Empty (TBE).
  1787.        bit 4 : BREAK detect.
  1788.        bit 3 : Framing error.
  1789.        bit 2 : Parity error.
  1790.        bit 1 : Overrun error.
  1791.        bit 0 : Data Ready.
  1792.  
  1793.   REG 6 : Modem Status
  1794.  
  1795.   Reading the Modem Status register provides the following status  information
  1796.   (1 for TRUE, 0 for FALSE) :
  1797.  
  1798.        bit 7 : DCD status.
  1799.        bit 6 : RI status.
  1800.        bit 5 : DSR status.
  1801.        bit 4 : CTS status.
  1802.        bit 3 : Delta DCD status.
  1803.        bit 2 : Delta RI status.
  1804.        bit 1 : Delta DSR status.
  1805.        bit 0 : Delta CTS status.
  1806.  
  1807.   The delta bits (bits 0 through 3) are set whenever one of  the  status  bits
  1808.   (bits  4 through 7) changes (from 0 to 1 or from 1 to 0) since the last time
  1809.   the Modem Status register was read. Reading the Modem Status register clears
  1810.   the delta bits.
  1811.  
  1812.   REG 7 : Scratch Register
  1813.  
  1814.   There  is  no  function  associated  with  register 7.  It does not exist in
  1815.   earlier versions of the 8250.
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  PCL4W Users Manual                                                Page 27
  1837.   7.0 Example Programs
  1838.  
  1839.  
  1840.   The  example programs can be built either using the command line makefile or
  1841.   directly from your compiler's IDE (see section 3.6 "Using and IDE").
  1842.  
  1843.  
  1844.   7.1 SIMPLE
  1845.  
  1846.   SIMPLE  is a very simple communications programming using PCL4W.  Everything
  1847.   that is typed on the keyboard is sent to  the  serial  port,  and  everthing
  1848.   incoming from the serial port is displayed on the screen.
  1849.  
  1850.      Using the Microsoft command line compiler: NMAKE SIMPLE._M_
  1851.      Using the Borland command line compiler:   MAKER -fSIMPLE._B_
  1852.      Using the Watcom command line compiler:    WMAKE -f SIMPLE._W_
  1853.  
  1854.   If you are using  the  Borland  IDE,  be  sure  and  turn  off  LINKER  case
  1855.   sensitivies:  Choose  OPTIONS,  PROJECTS,  LINKER,  GENERAL and turn off the
  1856.   "case sensitive link" and "case sensitive exports & imports" boxes.
  1857.  
  1858.   The SIMPLE makefiles use the small memory model. If a different memory model
  1859.   is  required,  the  Microsoft  (or  Borland)  runtime  library  must also be
  1860.   changed to match the memory model. No  change  is  required  for  the  PCL4W
  1861.   library.
  1862.  
  1863.   For example, to change the makefile from using the  small  memory  model  to
  1864.   using  the  medium  memory  model,  the following changes are necessary: For
  1865.   Microsoft, change -AS to -AM and change SLIBCEW to  MLIBCEW.   For  Borland,
  1866.   change -sm to -mm and change C0WS, CWS, and MATHWS to C0WM, CWM, and MATHWM.
  1867.  
  1868.   7.2 LOGIN
  1869.  
  1870.   LOGIN  is the same program as SIMPLE but with the addition of "Modem" on the
  1871.   menu bar.  Under "Modem", select "Start", then "Handshake" in order to  send
  1872.   an "AT" to the connected modem, or "Dial" to send a dial string to the modem
  1873.   (which  dials  our  user  support  BBS). Once the dial sequence is sent, the
  1874.   program will wait for up to 60 seconds for the  "CONNECT"  string  from  the
  1875.   modem.  This  wait  can  be terminated at any time by choosing "BREAK" under
  1876.   "Modem".
  1877.  
  1878.   To  test LOGIN, you need a AT command set compatible modem and a BBS to call
  1879.   up. LOGIN will dial our BBS at 205-880-9748, or  edit  the  dial  string  in
  1880.   LINE.C to call up a local BBS.
  1881.  
  1882.   7.3 SELFTEST
  1883.  
  1884.   SELFTEST performs a serial port I/O functionality test. A single port can be
  1885.   tested  if  a  loopback adapter is connected to the end of the serial cable.
  1886.   Refer to LOOPBACK.DOC for an explanation of how to make a loopback adapter.
  1887.  
  1888.   7.4 TERM
  1889.  
  1890.  
  1891.   TERM  is  an  example  communications  program suitable for calling bulletin
  1892.   board systems (BBS).
  1893.  
  1894.   TERM features modem initialization, hardware flow control, and state  driven
  1895.   file  transfer  using  ASCII,  XMODEM, and YMODEM, communications protocols.
  1896.   TERM can be used to  call  up  any  bulletin  board  system,  including  the
  1897.   MarshallSoft Computing BBS.
  1898.  
  1899.   In  an  attempt  to  minimize the size of the shareware version of the PCL4W
  1900.   library,  the  TERM  program  files  are  distributed  as  a  separate  file
  1901.   (WTERMxx.ZIP,  where  xx  is the current version). WTERMxx.ZIP can always be
  1902.   downloaded from the MarshallSoft support BBS.
  1903.  
  1904.  PCL4W Users Manual                                                Page 28
  1905.   8.0 Legal Issues
  1906.  
  1907.   8.1 Registration
  1908.  
  1909.  
  1910.   If you wish to register the PCL4W library, please send $75 plus $5 S&H  ($10
  1911.   outside of North America) to:
  1912.  
  1913.        MarshallSoft Computing, Inc.
  1914.        Post Office Box  4543
  1915.        Huntsville AL 35815-4543
  1916.  
  1917.   Multiple  copies  are  available: $60 each for 2 to 5, $45 each for 5 to 10,
  1918.   and $30 each for 20 or more.  A site license  is  also  available  for  $495
  1919.   (includes 5 sets of printed documentation). We pay shipping.
  1920.  
  1921.   We accept American Express, VISA, MasterCard, checks in US dollars drawn  on
  1922.   a   US   bank, International Postal Money Orders, purchase orders (POs) from
  1923.   recognized US schools and companies listed in  Dun  &  Bradstreet,  and  COD
  1924.   (street  address and phone number required) within the USA (plus a $4.50 COD
  1925.   charge).
  1926.  
  1927.   For  credit  card  orders,  be  sure  to  include  the  account  number, the
  1928.   expiration date, the exact name on the card, and the complete  card  billing
  1929.   address (the address to which the credit card bill is mailed).
  1930.  
  1931.   You can also order PCL4W from The Public Software Library  (PSL)  with  your
  1932.   MC,  Visa,  AmEx,  or  Discover card by calling 800-242-4PSL (from overseas:
  1933.   713-524-6394) or by FAX at 713-524-6398.  THESE  NUMBERS  ARE  FOR  ORDERING
  1934.   ONLY. The product number for PCL4W is 11171.
  1935.  
  1936.   Print the file PCL4W.INV if an invoice is needed.
  1937.  
  1938.   If you wish to update from an older version of PCL4W, send $25 plus  $5  S&H
  1939.   ($10  outside  of  North  America).   Updates  must be ordered directly from
  1940.   MarshallSoft Computing.
  1941.  
  1942.   The registered package includes:
  1943.  
  1944.        o  PCL4W Library w/o shareware screens.
  1945.        o  Assembler source code for the library.
  1946.        o  SCRIPT language V2.1 (compiler and interpreter).
  1947.        o  Laser printed Users and Reference Manuals.
  1948.        o  Telephone, BBS, and email support for one year.
  1949.  
  1950.   The  registered  user will receive the latest version of PCL4W shipped by US
  1951.   second day priority mail (packet airmail  overseas).   A  3.5"  diskette  is
  1952.   provided unless a 5.25" diskette is requested.
  1953.  
  1954.   All  prices  are guaranteed for one year from the release date as printed on
  1955.   the title page.
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  PCL4W Users Manual                                                Page 29
  1973.   8.2 License
  1974.  
  1975.  
  1976.   MarshallSoft  Computing,  Inc. grants the registered user of PCL4W the right
  1977.   to use one copy of the PCL4W library (in object form) on a  single  computer
  1978.   in  the  development  of  any software product (other than libraries such as
  1979.   PCL4W).  The user may not use the library on more than one computer  at  the
  1980.   same  time.   The  source code for the library (PCL4W.ASM) is copyrighted by
  1981.   MarshallSoft Computing and may not be released in whole or in part. Products
  1982.   developed using PCL4W may be distributed without any royalty.
  1983.  
  1984.  
  1985.   8.3 Warranty
  1986.  
  1987.  
  1988.   MARSHALLSOFT COMPUTING, INC.  DISCLAIMS  ALL  WARRANTIES  RELATING  TO  THIS
  1989.   SOFTWARE,  WHETHER  EXPRESSED  OR  IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
  1990.   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR  PURPOSE,
  1991.   AND  ALL  SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER
  1992.   MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN  INVOLVED  IN  THE
  1993.   CREATION,  PRODUCTION,  OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY
  1994.   INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT  OF  THE  USE  OR
  1995.   INABILITY  TO  USE  SUCH  SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.  HAS
  1996.   BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL
  1997.   MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH  DAMAGES  EVER  EXCEED
  1998.   THE  PRICE  PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM
  1999.   OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY
  2000.   AND PERFORMANCE OF THE SOFTWARE.
  2001.  
  2002.   Some states do not allow  the  exclusion  of  the  limit  of  liability  for
  2003.   consequential  or  incidental damages, so the above limitation may not apply
  2004.   to you.
  2005.  
  2006.   This agreement shall be governed by the laws of the  State  of  Alabama  and
  2007.   shall  inure  to  the  benefit  of  Marshallsoft  Computing,  Inc.   and any
  2008.   successors, administrators, heirs and  assigns.  Any  action  or  proceeding
  2009.   brought  by either party against the other arising out of or related to this
  2010.   agreement shall be brought only in a STATE or  FEDERAL  COURT  of  competent
  2011.   jurisdiction  located in Madison County, Alabama. The parties hereby consent
  2012.   to in personam jurisdiction of said courts.
  2013.  
  2014.  
  2015.  
  2016.  
  2017.  
  2018.  
  2019.  
  2020.  
  2021.  
  2022.  
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  PCL4W Users Manual                                                Page 30
  2041.   9.0 Summary
  2042.  
  2043.  
  2044.   9.1 Revision History
  2045.  
  2046.  
  2047.   Version 1.0: 1 February, 1994.
  2048.  
  2049.  
  2050.   The  initial  release  of  PCL4W uses a considerable amount of the code from
  2051.   version 4.0 of PCL4C (the DOS version of the comm library).
  2052.  
  2053.  
  2054.   Version 1.1:  August 1, 1994
  2055.  
  2056.  
  2057.   o A flow control bug was fixed.
  2058.   o COM11 through COM16 defined.
  2059.   o Supports the BB1004, BB1008, and BB2016 BOCA boards.
  2060.   o The new function SioGetDiv() was added.
  2061.   o A script compiler & interpreter was added to the registration package.
  2062.  
  2063.  
  2064.   Version 1.2:  August 8, 1995
  2065.  
  2066.  
  2067.   o Defined ports extended to 20.
  2068.   o Support for all IRQs [IRQ0 to IRQ15].
  2069.   o Bug in BREAK detection corrected.
  2070.   o Bug in SioRxClear fixed.
  2071.   o SioInfo also returns # interrupts.
  2072.  
  2073.  
  2074.   Version 1.3: July 8, 1996
  2075.  
  2076.   o SioRxFlush renamed SioRxClear.
  2077.   o SioTxFlush renamed SioTxFlush.
  2078.   o Added more choices in SioInfo.
  2079.   o Added LOGIN & SELFTEST example programs.
  2080.   o Simplified SIMPLE example program.
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  PCL4W Users Manual                                                Page 31
  2109.   9.2 Function Summary
  2110.  
  2111.   Refer  to the PCL4W Reference Manual (PCL4W.REF) for detailed information on
  2112.   the communications and  support  functions.  A  one  line  summary  of  each
  2113.   function follows:
  2114.  
  2115.   +--------------+-----------------------------------------------------------+
  2116.   |  SioBaud     |  Sets the baud rate of the selected port.                 |
  2117.   |  SioBrkSig   |  Asserts, cancels, or detects BREAK signal.               |
  2118.   |  SioCTS      |  Reads the Clear to Send (CTS) modem status bit.          |
  2119.   |  SioDCD      |  Reads the Data Carrier Detect (DCD) modem status bit.    |
  2120.   |  SioDone     |  Terminates further serial processing.                    |
  2121.   |  SioDSR      |  Reads the Data Set Ready (DSR) modem status bit.         |
  2122.   |  SioDTR      |  Set, clear, or read the Data Terminal Ready (DTR) bit.   |
  2123.   |  SioFIFO     |  Sets the interrupt level for the INS16550.               |
  2124.   |  SioFlow     |  Enables / disables hardware flow control.                |
  2125.   |  SioGetc     |  Reads the next character from the serial line.           |
  2126.   |  SioGetDiv   |  Gets the baud rate divisor.                              |
  2127.   |  SioInfo     |  Returns library ver number, memory model, # interrupts   |
  2128.   |  SioIRQ      |  Assigns an IRQ line to a port.                           |
  2129.   |  SioLine     |  Reads the line status register.                          |
  2130.   |  SioLoopBack |  Performs a UART loopback test.                           |
  2131.   |  SioModem    |  Reads the modem status register.                         |
  2132.   |  SioParms    |  Sets parity, stop bits, and word length.                 |
  2133.   |  SioPorts    |  Sets # ports, 1st DigiBoard port & status register.      |
  2134.   |  SioPutc     |  Transmit a character over a serial line.                 |
  2135.   |  SioRead     |  Reads any of 7 UART ports.                               |
  2136.   |  SioReset    |  Initialize a serial port for processing.                 |
  2137.   |  SioRI       |  Reads the Ring Indicator (RI) modem status bit.          |
  2138.   |  SioRTS      |  Sets, clears, or reads the Request to Send (RTS) line.   |
  2139.   |  SioRxBuf    |  Sets up receive buffer.                                  |
  2140.   |  SioRxClear  |  Clears the receive buffer.                               |
  2141.   |  SioRxQue    |  Returns the number of characters in the receive queue.   |
  2142.   |  SioTxBuf    |  Sets up transmit buffer.                                 |
  2143.   |  SioTxClear  |  Clears the transmit buffer.                              |
  2144.   |  SioTxQue    |  Returns the number of characters in the transmit queue.  |
  2145.   |  SioUART     |  Sets the UART base address.                              |
  2146.   |  SioUnGetc   |  "Un-gets" (puts back) a specified character.             |
  2147.   +--------------+-----+-----------------------------------------------------+
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  PCL4W Users Manual                                                Page 32
  2177.   9.3 Further Reading
  2178.  
  2179.  
  2180.   The  best way to learn about serial communications is to read a good book on
  2181.   the subject. Several good texts are available.  Two that I like are:
  2182.  
  2183.   (1) C Programmers's Guide to Serial Communications by  Joe  Campbell  (SAMS)
  2184.   (2) Mastering Serial Communications by Peter Gofton (SYBEX).
  2185.  
  2186.  
  2187.   10.0 Other MarshallSoft Computing Products
  2188.  
  2189.  
  2190.   The following shareware  libraries  are  also  available  from  MarshallSoft
  2191.   Computing.   They  can  be  registered  directly  through us.
  2192.  
  2193.   10.1 The Personal Communications Library for C/C++
  2194.  
  2195.   The Personal Communications Library for the C  Language  (PCL4C)  is  a  DOS
  2196.   based  asynchronous communications library designed for experienced software
  2197.   developers programming  in  C.   Four  compilers  are  supported:  Microsoft
  2198.   Optimizing  C,  Microsoft Quick C, Borland Turbo C, and MIX Power C.  An IBM
  2199.   PC/XT/AT or compatible is required.  PCL4C is the DOS equivalent of PCL4W.
  2200.  
  2201.   The Personal Communications Library for C (PCL4C) is available for $75  plus
  2202.   $5  S&H ($10 S&H overseas). PCL4C and PCL4W can be ordered together for $120
  2203.   plus $5 S&H ($10 overseas).
  2204.  
  2205.   10.2 Libraries for Other Languages
  2206.  
  2207.   We  also have communications libraries for Turbo Pascal, Visual Basic (DOS),
  2208.   and PowerBASIC.  A Visual BASIC library for Windows is also available.
  2209.  
  2210.  
  2211.  
  2212.  
  2213.  
  2214.  
  2215.  
  2216.  
  2217.  
  2218.  
  2219.  
  2220.  
  2221.  
  2222.  
  2223.  
  2224.  
  2225.  
  2226.  
  2227.  
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  PCL4W Users Manual                                                Page 33
  2245.